供应商详情资源信息分页 API 接口规范

1. 接口概览

GET/admin/supplier/items/{supplierId}/resource-info/page

用于供应商管理详情页“资源信息”页签，分页展示该供应商当前有效关系对应的资源权威信息。关系来源为本系统 supplier_resource_rel；Resource 提供九类本地资源，Fleet 提供车辆资源。

实现状态已实现 · 可联调

调用方管理后台；前端接入待完成

数据副作用无写库、Redis、MQ、配置或审计副作用

契约真相本文以合并提交 4f032cd6f 的 Controller、请求/响应 VO、Service 权限门禁及 TEST Gateway 验收为准。

2. 请求契约

2.1 路径与查询参数

参数	位置	类型	必填	约束与默认值
`supplierId`	path	string	是	正整数；Snowflake ID 必须按字符串传递
`page`	query	integer	否	默认 1，最小 1；公共分页兼容 `pageNo`
`pageSize`	query	integer	否	默认 20，范围 1..100
`resourceModule`	query	string	否	为空查询全部；非空按关系冻结模块精确筛选

2.2 支持的资源模块

编码	moduleName	数据归属
`SCENIC`	景区管理	Resource
`RESTAURANT`	餐厅管理	Resource
`SUPPLIES`	备品管理	Resource
`SUPPLIES_COMBO`	组合配品	Resource
`ACTIVITY`	游玩项目管理	Resource
`HOTEL`	酒店管理	Resource
`SERVICE`	服务管理	Resource
`COST_ITEM`	额外成本	Resource
`STAFF`	服务人员管理	Resource
`VEHICLE`	车队管理-车队管理	Fleet（内部批量聚合）

2.3 调用示例

GET /admin/supplier/items/2091715622923657217/resource-info/page?page=1&pageSize=20&resourceModule=SCENIC
Authorization: Bearer <有效管理端访问令牌>

权限是双门禁服务端仅允许 ADMIN、FINANCE、SUPER_ADMIN，并同时要求 supplier:view 与 supplier:resource:view。不能只通过隐藏页签代替服务端授权。

3. 响应结构

统一返回 Result<PageResult<SupplierResourceInfoRespVO>>。业务失败通常仍是 HTTP 200，调用方必须检查 code、success 与 message。

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "records": [
      {
        "relationId": "2091715622923657218",
        "resourceModule": "SCENIC",
        "moduleName": "景区管理",
        "resourceId": "2091715622923657001",
        "resourceName": "示例景区",
        "coverUrl": null,
        "city": "海拉尔",
        "isCharged": true,
        "isChargedName": "是",
        "settleTypeCode": "CASH",
        "settleTypeName": "现付",
        "tags": [
          { "tagId": "2084636804090089473", "tagName": "自然风光", "tagColor": "#52C41A" }
        ],
        "seasons": [
          { "seasonCode": "spring", "seasonName": "春" }
        ],
        "statusCode": "ENABLED",
        "statusName": "启用",
        "enabled": true,
        "resourceAvailable": true,
        "updateTime": "2026-08-25 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

4. records[] 字段

字段	类型	可空	说明
`relationId`	string	否	供应商资源关系 ID
`resourceModule`	string	否	关系冻结的资源模块编码
`moduleName`	string	否	模块中文名
`resourceId`	string	否	资源 ID；资源缺失仍保留关系原值
`resourceName`	string	是	当前资源名称
`coverUrl`	string	是	当前有效封面 URL
`city`	string	是	城市展示值
`isCharged`	boolean	是	是否收费；不适用/未知为 null
`isChargedName`	string	是	是否收费中文名
`settleTypeCode`	string	是	结算方式编码
`settleTypeName`	string	是	结算方式中文名
`tags`	array	否	标签列表；无数据为 []
`seasons`	array	否	标准季节列表；无数据为 []
`statusCode`	string	是	资源当前权威状态编码
`statusName`	string	是	归一化状态中文名
`enabled`	boolean	是	归一化启用标记
`resourceAvailable`	boolean	否	false 表示关系保留但资源已删除/缺失
`updateTime`	string	是	资源本身更新时间；yyyy-MM-dd HH:mm:ss

4.1 子结构

数组	字段	说明
`tags[]`	`tagId`、`tagName`、`tagColor`	标签 ID 沿用各资源模块的字符串表达
`seasons[]`	`seasonCode`、`seasonName`	标准季节编码与中文名

5. 业务口径

只读取当前有效的供应商资源关系，按关系 update_time DESC, rel_id DESC 稳定排序。
响应中的 updateTime 是资源主数据更新时间，不是关系更新时间。
标量字段不适用、未知或资源缺失时返回 null；tags 与 seasons 永远返回数组。
资源被软删除或不存在时不丢弃关系行：resourceAvailable=false，名称、状态、更新时间等当前资源字段为 null。
十类资源以本系统权威数据为准；展示形式可参考现有资源列表，但不要从参考图硬编码字段值或状态。
供应商处于草稿、审批中、合作中、暂停、黑名单、归档等任意生命周期状态时均可只读查询。
Fleet/字典依赖出现空响应、非成功、重复、缺失、额外或非法数据时返回 395039，不降级为部分成功。

内部依赖说明Resource 通过内部 Token 调用 POST /internal/fleet/vehicles/supplier-resource-info/batch 聚合车辆信息。该路径不面向管理端，前端不得调用、转发或持有内部 Token。

6. 错误码

业务码	场景	管理端建议
`401`	未认证或登录态失效	按统一登录续期/退出逻辑处理
`400`	supplierId、page 或 pageSize 等参数不合法	修正请求，不自动重试
`395001`	供应商不存在	关闭失效详情或刷新列表
`395034`	resourceModule 不受支持	仅使用本文十个稳定编码
`395039`	Fleet、字典或资源必要依赖不可用/响应不完整	提示稍后重试，不展示旧数据冒充成功

{
  "code": 395034,
  "message": "不支持的资源模块",
  "data": null,
  "success": false
}

7. 管理端接入清单

在供应商详情“账号信息”页签后新增“资源信息”页签；仅在页签打开时加载数据。
建议列：资源名称（封面 + 名称）、资源模块、城市、是否收费、结算方式、标签、季节、状态、更新时间。
所有 ID 按字符串保存、传参和比较，禁止转换为 JavaScript number。
优先展示服务端中文字段；未知字段显示“—”，不得前端猜测状态或字典名称。
resourceAvailable=false 时保留行并明确显示“资源已删除/不可用”。
模块筛选或页容量改变时回到第 1 页；pageSize 最大 100。
按 code/success 判断业务结果；不要仅依据 HTTP 200。
页签为只读展示，不增加绑定、改绑、解绑、启停或删除按钮。

7.1 建议验收场景

场景	预期
有资源关系	按分页显示，中文字段、数组、字符串 ID 正常
无资源关系	records=[]、total=0，不显示错误空态
按模块筛选	返回行的 resourceModule 全部等于筛选值
关系存在但资源缺失	保留关系行，resourceAvailable=false
无双权限/未登录	服务端拒绝，页面不泄露数据
依赖暂不可用	展示 395039 对应提示，不展示不完整成功页

8. 实现与验收状态

代码：PR #6330 已合并 dev-v3，合并提交 4f032cd6f6698607a2f1524437533d595975fc9a。
自动化：Resource 全量 2043 项零失败；Fleet 可运行全量 3853 项零失败；GatewayRouteAuditTest 3 项零失败；独立审计套件再次通过。
TEST：任务 cc1fe248、2697d374 精确部署同一合并提交，Resource/Fleet 双实例与 Nacos 各 2 实例健康。
真实 Gateway：有效管理端会话只读查询 3 个供应商，实际取得 1 条 SCENIC 关系；18 字段、字符串 ID、数组、时间和模块筛选均通过。
负向：395001、395034、page/pageSize 参数 400 与未认证 401 均实测通过。
车辆样本：TEST 当时无 VEHICLE 供应商关系；未伪造数据，跨服务路径由双服务真实部署健康与内部契约/批量/失败关闭测试覆盖。
环境恢复：任务 45e843e5、c05eda6e 已回切包含本次合并的 dev-v3；Resource 8082/8182、Fleet 8087/8187 及 Nacos 各 2 个实例健康，临时部署分支已删除。

数据清理TEST 验收全部为 GET 只读请求，没有创建或修改供应商、资源、数据库、Redis、MQ 或配置数据。

9. 撤回方案

从最新 dev-v3 创建回退分支，执行 git revert -m 1 --no-edit 4f032cd6f6698607a2f1524437533d595975fc9a，经独立 PR 合入。
依次重新构建并滚动部署 Resource、Fleet，分别保持双实例可用。
本次无数据库、Redis、MQ、Nacos 或其他配置变更，无需 DDL、DML、缓存清理、消息补偿或配置恢复，也无不可逆影响。
管理端停止调用新增 GET 和读取本次字段；既有供应商详情、账号和资源管理接口不受影响。
经 Gateway 复测新增路径撤回、既有供应商详情正常，并确认两服务双实例和 Nacos 健康。